Skip to content

gh-156866: Document that pack_into() does not guarantee memory access shape - #162078

Open
themythofsisyphusjayant wants to merge 1 commit into
python:mainfrom
themythofsisyphusjayant:fix-gh-156866-pack-into-mmio
Open

themythofsisyphusjayant wants to merge 1 commit into
python:mainfrom
themythofsisyphusjayant:fix-gh-156866-pack-into-mmio

Conversation

@themythofsisyphusjayant

@themythofsisyphusjayant themythofsisyphusjayant commented Nov 16, 2026 •

Copy link
Copy Markdown

The struct.pack_into() documentation says it writes the packed bytes into
a writable buffer, but says nothing about the underlying memory accesses
used to perform the write. For ordinary memory that does not matter, but it
is misleading when the buffer is backed by memory-mapped I/O (MMIO), where
the number, width, and ordering of actual memory accesses can be
semantically significant — a single pack_into("<I", ...) call was observed
to produce three native stores.

This adds a note to the pack_into() documentation (using the wording
suggested in the issue): pack_into() specifies the packed bytes written
to the buffer, but does not guarantee the number, width, or ordering of the
underlying native memory accesses. Writable buffers backed by MMIO should
not be treated as exact-width register access interfaces. The Struct.pack_into
method needs no change — it is documented as identical to the function.

Checked by building the page with Sphinx (9.1.1, from
Doc/requirements.txt): the page renders with the new note. The only build
warnings are pre-existing single-file-build artifacts, identical before and
after the change.

Disclosure: I used an AI coding assistant to help prepare this change, and
reviewed the diff myself before submitting.

@read-the-docs-community

Copy link
Copy Markdown

Documentation build overview

📚 cpython-previews | 🛠️ Build #35916406 | 📁 Comparing b9f54fb against main (7c59816)

  🔍 Preview build  

1 file changed
± library/struct.html

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

awaiting review docs Documentation in the Doc dir skip news

Projects

Status: Todo

Development

Successfully merging this pull request may close these issues.

1 participant